Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 4 - Dialog Manager Reference / Dialog Manager Functions

Creating Alerts /

StopAlert

CHANGED WITH THE APPEARANCE MANAGER

Displays an alert box with a stop icon in its upper-left corner (or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box).

pascal short StopAlert (short alertID, ModalFilterUPP modalFilter);

alertID

The resource ID of an alert resource and extended alert resource. The resource ID of both types of resources must be identical. If the alert resource is missing, the Dialog Manager returns to your application without creating the requested alert.

modalFilter

A universal procedure pointer for a filter function that responds to events not handled by the ModalDialog function. If you set this parameter to nil, the Dialog Manager uses the standard event filter function.

function result

If no stop alert box is to be drawn at the current alert stage, StopAlert returns -1; otherwise, it creates and displays the alert box and returns the item number of the control selected by the user; see "Alert Button Constants".

DISCUSSION

The StopAlert function is the same as the Alert function except that, before drawing the items in the alert box, StopAlert draws the stop icon in the upper-left corner. The stop icon has resource ID 0, which you can also specify with the constant stopIcon . By default, the Dialog Manager uses the standard stop icon from the System file. You can change this icon by providing your own 'ICON' resource with resource ID 0.

Use a stop alert to inform the user that a problem or situation is so serious that the action cannot be completed. Stop alerts typically have only a single button (OK), because all the user can do is acknowledge that the action cannot be completed.

IMPORTANT

Your application should never draw its own default rings or alert icons. Prior to Mac OS 8, the StopAlert function would only redraw the alert icon and default button ring once and never redraw them on an update event. However, when Appearance is available, alert icons and default rings do redraw when you call StopAlert.

SEE ALSO

NoteAlert.

CautionAlert.

WHEN THE APPEARANCE MANAGER IS NOT AVAILABLE

StopAlert only reads in the resource ID of an alert resource, not an extended alert resource.